Motivation and Context

Implements SEP-2243 (HTTP Header Standardization) for both client and server Streamable HTTP transports. This enables network infrastructure (load balancers, proxies, gateways) to make routing and filtering decisions based on MCP request metadata without parsing the JSON-RPC body.

Fixes #1541.

Changes

Protocol & Constants

• Add McpHttpHeaders static class with standard header name constants (Mcp-Method, Mcp-Name, Mcp-Param-*, etc.)
• Add DRAFT-2026-v1 as a supported protocol version for header enforcement
• Add McpErrorCode.HeaderMismatch (-32001) for header validation failures

Client-side (ModelContextProtocol.Core)

• StreamableHttpClientSessionTransport emits Mcp-Method, Mcp-Name, and Mcp-Param-* headers on all outgoing POST requests
• McpHeaderEncoder handles value encoding (plain ASCII pass-through, Base64 wrapping with =?base64?...?= sentinel for non-ASCII/control characters/leading-trailing whitespace)
• McpHeaderExtractor (internal) reads x-mcp-header annotations from tool schemas and adds corresponding Mcp-Param-{Name} headers
• Client validates tool schemas from tools/list and rejects tools with invalid x-mcp-header annotations (empty names, invalid characters, case-insensitive duplicates, non-primitive types)

Server-side (ModelContextProtocol.AspNetCore)

• StreamableHttpHandler validates incoming Mcp-Method and Mcp-Name headers match the JSON-RPC body (enforced only for DRAFT-2026-v1+)
• Validates Mcp-Param-* custom headers against tool schema x-mcp-header annotations and body argument values
• Returns 400 Bad Request with HeaderMismatch (-32001) JSON-RPC error on validation failure

Tool Authoring (ModelContextProtocol.Core)

• [McpHeader("Name")] attribute marks tool parameters for header mirroring
• AIFunctionMcpServerTool emits x-mcp-header extension in the tool's JSON schema for annotated parameters
• Validates at registration time: primitive types only, case-insensitive unique names, valid ASCII characters

Protocol Version Gating

Header validation is only enforced when the client's MCP-Protocol-Version header is DRAFT-2026-v1 or later. Clients on older protocol versions are unaffected. The client always sends headers on Streamable HTTP transport regardless of version (additive, non-breaking).

New Public API Surface

ModelContextProtocol.Protocol.McpHttpHeaders (static class)

public static class McpHttpHeaders
{
    // Version gating
    public static readonly string MinVersionForStandardHeaders; // "DRAFT-2026-v1"
    public static bool SupportsStandardHeaders(string? protocolVersion);

    // Standard header name constants
    public const string SessionId = "Mcp-Session-Id";
    public const string ProtocolVersion = "MCP-Protocol-Version";
    public const string LastEventId = "Last-Event-ID";
    public const string Method = "Mcp-Method";
    public const string Name = "Mcp-Name";
    public const string ParamPrefix = "Mcp-Param-";
}

ModelContextProtocol.Protocol.McpHeaderEncoder (static class)

public static class McpHeaderEncoder
{
    // Typed overloads for compile-time safety
    public static string? EncodeValue(string? value);
    public static string EncodeValue(bool value);
    public static string EncodeValue(long value);
    public static string EncodeValue(double value);

    // General-purpose overload (supports all numeric types)
    public static string? EncodeValue(object? value);

    // Decoding (case-insensitive Base64 prefix detection)
    public static string? DecodeValue(string? headerValue);
}

ModelContextProtocol.Server.McpHeaderAttribute (attribute)

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property)]
public sealed class McpHeaderAttribute : Attribute
{
    public McpHeaderAttribute(string name);
    public string Name { get; }
}

ModelContextProtocol.McpErrorCode (enum addition)

public enum McpErrorCode
{
    HeaderMismatch = -32001,  // New
    // ... existing values unchanged
}

How Has This Been Tested?

The PR includes comprehensive tests covering:

• Unit tests: McpHeaderEncoderTests — encode/decode round-trips, Base64 edge cases, type conversion, empty/null handling
• Unit tests: McpHeaderAttribute validation and schema generation
• Conformance tests: Sep2243HeaderTests — server-side header validation (method/name mismatch, missing headers, Base64 encoding, version gating, custom parameter headers)
• Integration tests: End-to-end client→server header flow via in-memory transport

Conformance tests are aligned with conformance repo PR #259.

All existing tests continue to pass (~8,000+ across net8.0, net9.0, net10.0, net472).

Breaking Changes

No breaking changes.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed